I should point out I also modified how the Config class constants are defined, and how they get type-cast, because it annoyed me when adding new Config options. That's probably way out of scope and totally my personal preference.

Let me know if that's an unacceptable change.

First of all, let me thank you for trying out this package and creating such a great pull request.
It has all information I need to understand your case.

To the issue:

Your observation is correct an expected, that this autoloader has to be the only loader for classes that have an alias defined. If this is not the case, then you will run into all sorts of issues. Let me explain the why in more detail by going to each case that can happen.

1. An alias class name is requested by the application

Given we have a class name NewClass, which has exactly one legacy class name LegacyClass, which should be made an alias for compatibility reasons.

If the application uses LegacyClass the following must happen:

1. The class file of NewClass needs to be loaded
2. The alias needs to be established by executing class_alias('NewClass', 'LegacyClass')

That is the easiest and least problematic case.
Given we had a stack of two autoloaders ApcClassLoader on top, thus triggered first, and ClassAliasLoader as second. The ApcClassLoader isn't aware of the alias, thus ClassAliasLoader is triggered. It will first load the LegacyClass class file and the establish the alias.

Everything is fine for this case.

2. A class name, which has an alias, is requested by the application

Given we have a class name NewClass, which has exactly one legacy class name LegacyClass, which should be made an alias for compatibility reasons.

If the application uses NewClass the following must happen:

1. The class file of NewClass needs to be loaded
2. The alias needs to be established by executing class_alias('NewClass', 'LegacyClass')

These two steps need to be done be exactly one autoloader, otherwise you'll run into trouble. Here is why:

Given we had a stack of two autoloaders MyClassLoader on top, thus triggered first, and ClassAliasLoader as second.
Given MyClassLoader is able to find and load NewClass.

MyClassLoader is aware of NewClass and loads it without establishing LegacyClass as alias.

Everything is still working to some extend. If the application would now need LegacyClass, e.g. by creating an instance of it new LegacyClass(), PHP will trigger the autoloading again and we would go back to case one.

However, consider code like this:

interface A {
    public function(NewClass $newClass);
}

class B implements A {
    public function(LegacyClass $newClass) {}
}

If NewClass is already known by PHP, but LegacyClass not, because the the alias is not yet established, PHP will not trigger the autoloader again and just throws a fatal error.

Options

There are multiple options to fix this.

1. Implement your own ApcClassLoader, which also stores the aliases into apcu and establish the aliases in case of a cache hit
2. Use PHP 5.6 or higher and change ClassAliasLoader to store the alias maps in static properties of a generated class. This is the same optimization the composer class loader has undergone and will most likely make ApcClass loader obsolete, because this class will stay in OpCache memory after the first hit.
3. If you really only have a few aliased classes and it does not harm your performance to load these classes and establish the aliases upfront, then just create a plain PHP file and set it as include un your composer configuration of the package in question. The you won't need this package any more

Conclusion

This alias loader package was designed to be able to deal with many classes and aliases. The option you introduced in the pull request, adds support for an edge case where only a few aliases are present. So it basically contradicts the initial intention of the package. This is the reason why I unfortunately cannot accept this PR as is.

Nevertheless I'm here to support you. I planned to implement option 2 anyway, so that we benefit from this speed gain ourselves. I will start implementing this now. By doing so, I will introduce API, that you can also go for option 1, which isn't easily possible now because of limitations in the API.

So I hope you won't choose option 3 and give this package another shot in the (near) future :)

If you don't mind, if I will consider your changes to the Config class in the refactoring I'm starting now. I'll try to cherry-pick this commit if possible.

@helhum thanks for coming back with the detailed explanation. The autoloader system isn't something I'm intimately familiar with.

I fully agree with you about this being an edge-case for the ClassAliasLoader, and it definitely goes against the grain of the autoloader, but I don't think it's entirely out-of-bounds for this library as a feature.

If you really only have a few aliased classes and it does not harm your performance to load these classes and establish the aliases upfront, then just create a plain PHP file and set it as include un your composer configuration of the package in question. The you won't need this package any more

I'm fully aware that our application code is still growing, so eventually it won't be practical to use this alias force-loading mechanism, and we will have to migrate our system to use the class-alias-loader's real autoloader.
With that in mind, I'd much rather our developers wrote code that's compatible with the ClassAliasLoader rather than using raw class_alias calls from randomly included scripts dotted around our system.

I mean, I could make them specify the aliases in an array format that's compatible with class-alias-loader, and then i could write something that loads those alias mappings from a list of files that i make people specify somewhere (composer.json perhaps?) ... but I'm sure you can see where I'm going with this :)

This PR is option 3. It connects the dots between using class_alias by itself, and switching to the ClassAliasLoader autoloader. If someone was looking for a graceful upgrade path, this would be it.

I agree this feature is risky because of performance questions - you should absolutely know what you're doing before you opt into using the forced preloader. If you don't want to support that feature (and I can understand why) then I'm happy for you to discard this PR.

Unfortunately for us, it's too dangerous to modify our autoloader(s) at this time, so we'll be opting to use this branch and (hopefully) maintain compatibility with class-alias-loader until the issues can be solved (which will either be when performance issues become noticeable, ApcClassLoader becomes fully redundant, or ClassAliasLoader gets an update that happens to make it compatible).

Also, totally happy for you to cherry pick any of this PRs code, so no worries there.

OK. As said, I'm happy to help here and make this package more useful for other cases.
To do so: can you tell me what PHP version your application relies on? I'm currently considering to throw away legacy in the code base here, which was only needed for the time being and moving to a cleaner (and faster) approach. While doing so, I will definitely raise the minimum PHP requirement and ask myself if it makes sense to go for PHP 7 or if PHP 5.5 or 5.6 is better for users of this lib.

Do you have an opinion here?

Besides that, I reconsider merging your feature to the current branch and do the refactoring/rewrite in another one. This way, you could rely on a released version of this package (let's say 1.1.0), while I'm developing 2.0, where I definitely drop all the case insensitive class name handling and raise the minimum PHP requirement.

Give me some time however to get things straight here …

@helhum No worries, thanks for considering this further. We're happy to use branched code, but it is even better when we can use proper releases ;) No rush.

We're on PHP 5.6 at the moment, looking to upgrade to PHP7 in the next 6 months.
5.6 support would be ideal, although as this code needs to be as-fast-as-possible I could totally understand having two implementations - one for 5.6 (for BC/legacy) and another for 7+, if there's speed benefits to be had that aren't BC.